Overview of QTMA Components

These components are described in more detail in the following sections. Figure 1 illustrates the relationships among the various QTMA components.

Note Allocator Component

You use the note allocator component to play individual notes. Your application can specify which musical instrument sound to use and exactly which music synthesizer to play the notes on. The note allocator component can also display an Instrument Picker, which allows the user to choose instruments. The note allocator, unlike the tune player, provides no timing-related features to manage a sequence of notes. Its features are similar to a music component, although more generalized. Typically, an application opens a connection to the note allocator which in turn sends messages to the music component. An application or music track can include any number of timbres (parts).

To play a single note, your application must open a connection to the note allocator component and call NANewNoteChannel with a note request--typically to request a standard instrument within the General MIDI library of instruments. A note channel is similar in some ways to a Sound Manager sound channel, in that it needs to be created and disposed, and can receive various commands. The note allocator provides an application-level interface for requesting note channels with particular attributes. The client specifies the desired polyphony and the desired tone. The note allocator returns a note channel that best satisfies the request.

With an open note channel, an application can call NAPlayNote while specifying the note's pitch and velocity. The note is played and continues to play until a second call to NAPlayNote is made specifying the same pitch, but with a velocity of zero. The velocity of zero causes the note to stop. The note allocator functions let you play individual notes, apply a controller change, apply a knob change, select an instrument based on a required tone, and modify or change the instrument type on an existing note channel.

There are calls for registering and unregistering a music component. As part of registration, the MIDI connections, if applicable, are specified. There is also a call for querying the note allocator for registered music components, so that an application can offer a selection of the existing devices to the user.

Tune Player Component

The tune player component can accept entire sequences of musical notes and play them start to finish, asynchronously, with no further need for application intervention. It can also play portions of a sequence. An additional sequence or sequence section may be queued-up while one is currently being played. Queuing sequences provides a seamless way to transition between sections.

The tune player negotiates with the note allocator to determine which music component to use and allocates the necessary note channels. The tune player handles all aspects of timing, as defined by the sequence of music events. For more information about music events and the event sequence which is required to produce music in a QuickTime movie track, see the section "About QuickTime Music Events" .

The tune player also provides services to set the volume, and to stop and restart an active sequence.

If your application simply wants to play background music, it may be easier to use the QuickTime Movie Toolbox, rather than call the tune player directly.

Music Components Included in QuickTime

Individual music components act as device drivers for each type of synthesizer attached to a particular computer. Three music components are included in QuickTime:

The QuickTime Music Synthesizer component, for playing music out of a computer's built-in speaker
The General MIDI component, for playing music on a General MIDI device attached to a serial port.
The MIDI synthesizer, which allows QuickTime to control a synthesizer that is connected to a single MIDI channel.

Developers can add other music components for specific hardware and software synthesizers. To better understand the role of a music component, see "The QuickTime Music Synthesizer Component" .

Applications do not usually call music components directly. Instead, the note allocator or tune player handles music component interactions. Music components are mainly of interest to application developers who want to access the low-level functionality of synthesizers and for developers of synthesizers (internal cards, MIDI devices, or software algorithms) who want to make the capabilities of their synthesizers available to QuickTime.

In order for an application to call a music component directly, you must first allocate a note channel and then use NAGetNoteChannelInfo and NAGetRegisteredMusicDevice to get the specific music component and part number.

You can use music component functions to

obtain specific information about a synthesizer
find an instrument that best fits a requested type of sound
play a note with a specified pitch and volume
change knob values to alter instrument sounds

Other functions are for handling instruments and synthesizer parts. You can use these functions to initialize a part to a specified instrument and to get lists of available instrument and drum kit names. You can also get detailed information about each instrument from the synthesizer, and get information about and set knobs and controllers.

Instrument Components and Atomic Instruments

QuickTime 3 provides a public format for atomic instruments. These sounds may be embedded in a QuickTime movie, passed via a call to QuickTime, or dropped into the System Folder.

When initialized, the note allocator searches for components of type `inst' . These components may report a list of atomic instruments.

Atomic Instrument Format

The sounds are called atomic instruments, because you create them with QT atoms. (QT atoms are described in Chapter 1, "Movie Toolbox.") Using the QuickTime calls for manipulating atoms, you construct in memory a hierarchical tree of atoms with the data that describes the instrument (see Figure 2 ). The tree of atoms lives inside an atom container. There is one and only one root atom per container. Each atom has a four-character (32-bit) type, and a 32-bit ID. Each atom may be either an internal node, or a leaf atom with data.

Figure 2 An atomic instrument atom container.